%
%  AmiCo Documentation
%
%  Created by Sergey Karakovskiy on 2010-02-17.
%  Copyright (c) 2010 IDSIA. All rights reserved.
%
\documentclass[12pt]{article}
% \documentclass[11pt]{article}
\usepackage{amsthm,amsmath,amssymb}

% Use utf-8 encoding for foreign characters
\usepackage[utf8]{inputenc}
\usepackage{tikz}
\usetikzlibrary{arrows,shapes,snakes,automata,backgrounds,petri}

% \usepackage{pdfsync}

% Setup for fullpage use
\usepackage{fullpage}

% Uncomment some of the following if you use the features
%
% Running Headers and footers
%\usepackage{fancyhdr}

% Multipart figures
%\usepackage{subfigure}

% More symbols
%\usepackage{amsmath}
%\usepackage{amssymb}
%\usepackage{latexsym}

% Surround parts of graphics with box
\usepackage{boxedminipage}

% Package for including code in the document
\usepackage{listings}

% If you want to generate a toc for each chapter (use with book)
\usepackage{minitoc}

% This is now the recommended way for checking for PDFLaTeX:
\usepackage{ifpdf}

%\newif\ifpdf
%\ifx\pdfoutput\undefined
%\pdffalse % we are not running PDFLaTeX
%\else
%\pdfoutput=1 % we are running PDFLaTeX
%\pdftrue
%\fi

% \ifpdf
% \usepackage[pdftex]{graphicx}
% \else
% \usepackage{graphicx}
% \fi
\title{AmiCo \\ Cross platform library for effective interlanguage communication.}
\author{ Sergey Karakovskiy }

\date{\today}

\begin{document}

\ifpdf
\DeclareGraphicsExtensions{.pdf, .jpg, .tif}
\else
\DeclareGraphicsExtensions{.eps, .jpg}
\fi

\maketitle

\begin{abstract}
	The range of usage of benchmarks and algorithms is significantly limited by the programming language they are implemented in, e.g. algorithms written in \texttt{Python} cannot be directly evaluated by benchmarks implemented in \texttt{Java}. The common overcome of usage \emph{TCP} or \emph{UDP} as interface for communication decreases the performance significantly and this becomes a huge problem where lots of trials are necessary to perform any learning strategy. \texttt{AmiCo} allows to bridge different programming languages through their native bindings to \texttt{C++}.  This approach improves significantly the quality of evaluation of different algorithms against widen range of benchmarks. In \texttt{AmiCo Tutorial.pdf} there is an example of a \texttt{Python} agent evaluation by \texttt{Mario AI} benchmark implemented in \texttt{Java}.
\end{abstract}

\section{Introduction}
This \texttt{AmiCo} document covers bridging \texttt{Java} and \texttt{Python}. It uses \texttt{JNI} for the connection with \texttt{Java} and \texttt{ctypes} from standard \texttt{Python} disribution. This document contains description of bridging in both directions: \emph{Java Calls Python} and \emph{Python Calls Java}. Platform specific issues about building the library are described in \emph{Platform specifics} section. Several scenarios are possible and all of them have their impact on performance. Here we distinguish \emph{active} and \emph{passive} code. \emph{Active} uses \texttt{AmiCo}, \emph{passive} code is implemented in such a way that it even has no idea that it's gonna be bridged with another programming language natively. In most of the cases the benchmark is an active application and the implemented algorithm is the \emph{passive} one, but it's optional. In general this is summarized in Figure~\ref{fig:amicoScheme}. More concrete example is shown in Figure~\ref{fig:amicoConcrete}. 
\begin{figure}[htbp]
	\centering
		\includegraphics[scale=.7]{amicoScheme.pdf}
	\caption{Concrete Scheme of \texttt{AmiCo} integration. Here we have \texttt{Mario AI} benchmark}, which uses \texttt{AmiCo} and an agent in \texttt{Python} that has previously been used through \texttt{TCP} interface.
	\label{fig:amicoScheme}	
\end{figure}
\begin{figure}[htbp]
	\centering
		\includegraphics[scale=.7]{amicoSchemeGeneral.pdf}
	\caption{General Scheme of \texttt{AmiCo} integration. Several agents and benchmarks can be bridge with a single library.}
	\label{fig:amicoSchemeGeneral}	
\end{figure}

\subsection{General workflow}
\label{sub:common}

% subsection mac_os_x (end)
\subsubsection{Java Calls Python} % (fold)
\label{sub:java_calls_python}
\begin{enumerate}
	\item \texttt{unzip} the archive \texttt{AmiCoDemo.zip}
	\item Create file \texttt{JavaCallsPython.py} in the root of the project. It's a simple Python file. Any user code, any library code, compatible with you current Python environment is valid.
	\item Create a native caller method like in \\ \texttt{ch/idsia/amico/javacallspython/JavaCallsPython.java}: 
	\begin{verbatim}
	    	private native int mean(int a, int b); 		
	\end{verbatim}
	This means that this method is going to be method implemented using C/C++; 
	\item \texttt{javac6 ch/idsia/amico/javacallspython/JavaCallsPython.java}. This will produce \texttt{JavaCallsPython.class} in the same directory with the \texttt{JavaCallsPython.java} file.
	\item \texttt{javah6 -jni ch.idsia.amico.javacallspython.JavaCallsPython} will produce	 \texttt{ch\_idsia\_amico\_javacallspython\_JavaCallsPython.h} header for C/C++ \footnote{I'll stick to C++ and all comments will be regarding C++} in the project root directory (in this example on the same level with directory \texttt{ch}).
	\item Create an implementation \texttt{JavaCallsPython.cc} file and implement the native method for Java using a Python module \texttt{JavaCallsPython.py} created before. This file should contain includes of the \texttt{jni.h}, \\  \texttt{ch\_idsia\_amico\_javacallspython\_JavaCallsPython.h}, \texttt{Python/Python.h} headers and the implementation of the \texttt{mean} method.
\begin{verbatim}
	Py_Initialize();
	std::cout << "\nC++: Loading python stuff: ";
	PyObject* main_module = PyImport_ImportModule("JavaCallsPython");
	if (main_module == 0)
	    std::cout << "\nC++: Main module had not been loaded";
	PyObject* res = PyObject_CallMethod(main_module, "computeMean", "(ii)", a, b);
	long result = PyInt_AsLong(res) ;
	return result;
\end{verbatim}
\item Build \& Run! You might would like to create a shell-script like this:
\begin{verbatim}
	javac ch/idsia/amico/javacallspython/JavaCallsPython.java
	javah -jni ch.idsia.amico.javacallspython.JavaCallsPython
	g++ -dynamiclib -framework Python 
	 -I/System/Library/Frameworks/JavaVM.framework/Versions/Current/Headers 
	 ch_idsia_amico_javacallspython_JavaCallsPython.cc
	 -o libAmiCo.dylib # this should be in one line;
	java -Djava.library.path=. ch.idsia.amico.javacallspython.JavaCallsPython
\end{verbatim}
\end{enumerate}
% subsection java_calls_python (end)

\section{Platform specifics} % (fold)
\label{sec:platform_specifics}
Most of the platform specific issues are handled by the \texttt{Makefile}. So type \texttt{make} in the Demo project root and it will produce \texttt{libAmiCo.dylib} on \texttt{Mac OS X} and \texttt{libAmiCo.so} on \texttt{Linux} platforms.
% section platform_specifics (end)
\bibliographystyle{plain}
\bibliography{}
\end{document}
